 /*******************************************************************************
  * Copyright (c) 2000, 2005 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/

 package org.eclipse.ui.texteditor;


 import org.eclipse.core.runtime.CoreException;
 import org.eclipse.core.runtime.IStatus;


 /**
  * Extension interface for {@link IDocumentProvider}. It adds the following
  * functions:
  * <ul>
  * <li> dealing with immutable domain elements
  * <li> state validation
  * <li> persistent status of domain element operations
  * <li> extended synchronization support
  * </ul>
  * @since 2.0
  */
 public interface IDocumentProviderExtension {

     /**
      * Returns whether the document provider thinks that the given element is read-only.
      * If this method returns <code>true</code>, <code>saveDocument</code> could fail.
      * This method does not say anything about the document constructed from the given
      * element. If the given element is not connected to this document provider, the return
      * value is undefined. Document providers are allowed to use a cache to answer this
      * question, i.e. there can be a difference between the "real" state of the element and
      * the return value.
      *
      * @param element the element
      * @return <code>true</code> if the given element is read-only, <code>false</code> otherwise
      */
     boolean isReadOnly(Object element);

     /**
      * Returns whether the document provider thinks that the given element can persistently be modified.
      * This is orthogonal to <code>isReadOnly</code> as read-only elements may be modifiable and
      * writable elements may not be modifiable. If the given element is not connected to this document
      * provider, the result is undefined. Document providers are allowed to use a cache to answer this
      * question, i.e. there can be a difference between the "real" state of the element and the return
      * value.
      *
      * @param element the element
      * @return <code>true</code> if the given element is modifiable, <code>false</code> otherwise
      */
     boolean isModifiable(Object element);

     /**
      * Validates the state of the given element. This method may change the "real" state of the
      * element. If using, it also updates the internal caches, so that this method may also change
      * the results returned by <code>isReadOnly</code> and <code>isModifiable</code>. If the
      * given element is not connected to this document provider, the effect is undefined.
      *
      * @param element the element
      * @param computationContext the context in which the computation is performed, e.g., a SWT shell
      * @exception CoreException if validating fails
      */
     void validateState(Object element, Object computationContext) throws CoreException;

     /**
      * Returns whether the state of the given element has been validated.
      *
      * @param element the element
      * @return <code>true</code> if the state has been validated
      */
     boolean isStateValidated(Object element);

     /**
      * Updates the state cache for the given element. This method may change the result returned
      * by <code>isReadOnly</code> and <code>isModifiable</code>. If the given element is not
      * connected to this document provider, the effect is undefined.
      *
      * @param element the element
      * @exception CoreException if validating fails
      */
     void updateStateCache(Object element) throws CoreException;

     /**
      * Marks the document managed for the given element as savable. I.e.
      * <code>canBeSaved(element)</code> will return <code>true</code>
      * afterwards.
      *
      * @param element the element
      */
     void setCanSaveDocument(Object element);

     /**
      * Returns the status of the given element.
      *
      * @param element the element
      * @return the status of the given element
      */
     IStatus getStatus(Object element);

     /**
      * Synchronizes the document provided for the given element with the
      * given element. After that call <code>getSynchronizationTimeStamp</code>
      * and <code>getModificationTimeStamp</code> return the same value.
      *
      * @param element the element
      * @exception CoreException if the synchronization could not be performed
      */
     void synchronize(Object element) throws CoreException;
 }

